Order Rules Technical Implementation
This article is intended for a technical marketer or other technical resource responsible for implementing the necessary API requests to support Order Rules.
POS API Endpoints
Order Rules operate primarily through two Point of Sale (POS) API endpoints:
-
assign_member API: Projects potential point earnings.
-
submit_transaction API: Records final point calculations.
Bonus Summary
Loyalty provides an optional Order Rule feature called a Bonus Summary. When enabled, the API response to an order provides additional messaging to Members regarding Bonus Earn Rules for which their purchase qualifies, as well as any potential Bonus Earn Rules for which they could qualify if they include additional items in their purchase.
If enabled, the response from the assign_member endpoint includes a bonus_summary object that provides the following additional information:
-
applied_bonuses: Metrics earned from the Base Earn Rule and also any Bonus Earn Rules for which the transaction qualified.
-
non-applied_bonuses: Available Bonus Earn Rules for which the transaction did not qualify.
-
total bonus: Total Metrics earned from this transaction.
Below is a sample JSON response showing the structure of the Bonus Summary object.
The Bonus Summary feature can be enabled through a Program Setting. To enable this feature:
-
On the Program Settings screen, search for and select the Include Bonus Summary setting in the POS category.
-
From the Value drop-down menu, select True.
-
Click Save.
Sample Message: Assign Member endpoint
Request Message
Below is a sample request to the assign_member endpoint. In this example, the Member has purchased 5 items with a sub-total of $97.
curl --location --request PUT 'https:[hidden]//program/api/pos/stellar?access_token=[hidden]' \
--header 'Accept: application/vnd.stellar-v1+json' \
--header 'SL-Business-Unit: [hidden]' \
--header 'Content-Type: application/json'
--data '{
"audit": false,
"status": "assign_member",
"lock": "true",
"timestamp": "2025-05-22T07:00:00Z",
"business_date": "2025-05-22",
"linked_transaction": "",
"store_id": "12345",
"terminal_id": "2",
"transaction_id": "OR_Bonus_20250522_01",
"operator_id": "1",
"coupon_categories": [
],
"accounts": [
{
"identifier": "A-024238492",
"identifier_type": "member_id",
"profile": {}
}
],
"items": [
{
"level": 1,
"line_number": 1,
"parent_line_number": 0,
"name": "Item 1",
"description": "Qualified Item 1",
"sku": "5000",
"categories": ["GRILL"],
"quantity": 1,
"unit_price": 10.00,
"discountable": true
},
{
"level": 1,
"line_number": 2,
"parent_line_number": 0,
"name": "Item 2",
"description": "Non-Qualified Item",
"sku": "5500",
"categories": [],
"quantity": 1,
"unit_price": 12.00,
"discountable": true
},
{
"level": 1,
"line_number": 3,
"parent_line_number": 0,
"name": "Item 3",
"description": "Qualified Item 3",
"sku": "5190",
"categories": [],
"quantity": 1,
"unit_price": 15.00,
"discountable": true
},
{
"level": 1,
"line_number": 4,
"parent_line_number": 0,
"name": "Item 4",
"description": "Qualified Item 2",
"sku": "5190",
"categories": [],
"quantity": 1,
"unit_price": 10.00,
"discountable": true
},
{
"level": 1,
"line_number": 4,
"parent_line_number": 0,
"name": "Item 5",
"description": "Qualified Item 3",
"sku": "5190",
"categories": [],
"quantity": 1,
"unit_price": 50.00,
"discountable": true
}
],
"coupon_codes": [],
"coupons": [],
"summary": {
"gross_sales": "97.00",
"subtotal": "97.00",
"discount": "0.0",
"service_charge": "1.0",
"tax": "2.00",
"payment": "100.00",
"payment_status": "unpaid"
}
}Response Message
Below is the response to the above request.
{
"messages": {
"display": [
{
"code": 200,
"message": "Adding guest - John Smith.\\n\\nThe guest has no valid rewards.\\nPoints: 167\\nProjected Tier: 'base'\\nNo available Tier Rewards"
}
],
"error": [],
"receipt": null,
"bonus_summary": {
"applied_bonuses": [
{
"metric_earn": 97.0,
"bonus_display_name": "Order Rule Base",
"bonus_rule_description": ""
},
{
"metric_earn": 25.0,
"bonus_display_name": "Bonus Rule 1: Items",
"bonus_rule_description": "25 bonus points for purchasing qualified items"
},
{
"metric_earn": 45.0,
"bonus_display_name": "Bonus Rule 3: # of Qualified Items",
"bonus_rule_description": "45 bonus points for purchasing 3 qualified items"
}
],
"non_applied_bonuses": [
{
"bonus_display_name": "Bonus Rule 2: Minimum Order",
"bonus_rule_description": "50 bonus points for orders over $100"
}
],
"total_bonus": 167.0,
"metric": "point"
}
},
"accounts": [
{
"identifier": "A-024238492",
"valid": true,
"name": "John Smith",
"first_name": "John",
"last_name": "Smith",
"member_id": "A-024238492",
"new_metric_balance": "0",
"lifetime_metric_balance": "0",
"earned_metric_amount": 167
}
],
"summary": {
"gross_sales": "97.0",
"subtotal": "97.0",
"discount": "0.0",
"service_charge": "1.0",
"tax": "2.0",
"payment": "100.0",
"total": "100.0"
},
"details": {
"integration_id": "12345-OR_Bonus_20250522_01-20250522",
"linked_integration_id": "",
"metrics": {
"point": 167
},
"duplicate": false
},
"projection": {
"metric_amount": 167.0,
"metric": "point",
"new_tier": "Discoverer",
"new_tier_name": "base",
"eligible_rewards": []
},
"audit_trail": {}
}
In the response example above, the applied_bonuses array shows that the Base Earn Rule (Order Rule Base) and two Bonus Earn Rules (Bonus Rule 1: Items and Bonus Rule 3: # of Qualified Items) were applied to the transaction.
The total_bonus property indicates that the Member will earn 167 points upon finalizing this transaction:
-
97 points from the Base Earn Rule
-
25 points from Bonus Rule 1: Items
-
45 points from Bonus Rule 3: # of Items
The non_applied_bonuses array references an additional Bonus Earn Rule (Bonus Rule 2: Minimum Order) for which this transaction did not qualify. The Bonus Earn Rule description indicates the requirements needed to qualify:
-
50 bonus points for orders over $100: The Member can qualify for this Bonus Earn Rule by adding items to reach a subtotal of $100 or more.
If the Member follows these requirements to increase their subtotal, they would earn an additional 50 points.
Please note the importance of entering clear, descriptive descriptions of the Bonus Earn Rules, as those descriptions are included directly in the JSON response.
Sample Message: Submit Transaction
Request Message
Below is a sample request to the submit_transaction endpoint. This example continues the previous example. The Member has now completed their transaction.
curl --location 'https:[hidden]//program/api/pos/stellar?access_token=[hidden]' \
curl --location 'https:[hidden]//program/api/pos/stellar?access_token=[hidden]' \
--header 'Accept: application/vnd.stellar-v1+json' \
--header 'SL-Business-Unit: [hidden]' \
--header 'Content-Type: application/json' \
--data '{
"audit": false,
"status": "submit_transaction",
"timestamp": "2025-05-22T07:00:00Z",
"business_date": "2025-05-22",
"linked_transaction": "",
"store_id": "12345",
"terminal_id": "2",
"transaction_id": "OR_Bonus_20250522_01",
"operator_id": "1",
"coupon_categories": [
],
"accounts": [
{
"identifier": "A-024238492",
"identifier_type": "member_id",
"profile": {}
}
],
"items": [
{
"level": 1,
"line_number": 1,
"parent_line_number": 0,
"name": "Item 1",
"description": "Qualified Item 1",
"sku": "5000",
"categories": ["GRILL"],
"quantity": 1,
"unit_price": 10.00,
"discountable": true
},
{
"level": 1,
"line_number": 2,
"parent_line_number": 0,
"name": "Item 2",
"description": "Non-Qualified Item",
"sku": "5500",
"categories": [],
"quantity": 1,
"unit_price": 12.00,
"discountable": true
},
{
"level": 1,
"line_number": 3,
"parent_line_number": 0,
"name": "Item 3",
"description": "Qualified Item 3",
"sku": "5190",
"categories": [],
"quantity": 1,
"unit_price": 15.00,
"discountable": true
},
{
"level": 1,
"line_number": 4,
"parent_line_number": 0,
"name": "Item 4",
"description": "Qualified Item 2",
"sku": "5190",
"categories": [],
"quantity": 1,
"unit_price": 10.00,
"discountable": true
},
{
"level": 1,
"line_number": 4,
"parent_line_number": 0,
"name": "Item 5",
"description": "Qualified Item 3",
"sku": "5190",
"categories": [],
"quantity": 1,
"unit_price": 50.00,
"discountable": true
}
],
"coupon_codes": [],
"coupons": [],
"summary": {
"gross_sales": "97.00",
"subtotal": "97.00",
"discount": "0.0",
"service_charge": "1.0",
"tax": "2.00",
"payment": "100.00",
"payment_status": "paid"
}
}
Response Message
Below is the response to the above request. This message shows the points earned by the Member for this purchase.
{
"messages": {
"display": [
{
"code": 208,
"message": "Order - 12345-OR_Bonus_20250522_01-20250522 closed. Thank you and come again soon!"
}
],
"error": [],
"receipt": [
{
"message": "Timezone - 12345\r\nJakarta, Indonesia\r\n\r\nMay 22, 2025 14:00\r\nCheck #: OR_Bonus_20250522_01\r\n******************************************\r\n \r\n1.0 Qualified Item 3 50.0 \r\n1.0 Qualified Item 3 15.0 \r\n1.0 Non-Qualified Item 12.0 \r\n1.0 Qualified Item 1 10.0 \r\n1.0 Qualified Item 2 10.0\r\n\r\nSubtotal: 97.0\r\nTax: 2.0\r\nTotal: 100.0\r\n\r\nEarned for Each Metric:\r\n \r\n167 point\r\n******************************************\r\nMember: John Smith\r\nPhone #: \r\nCard #: \r\n------------------------------------------\r\nCurrent Earn: \r\nTotal Points: 0\r\nTotal TestMetric: 0\r\nTotal Spend: 0.0\r\n\r\nAvailable Offers for Next Purchase:\r\n",
"priority": 0
}
],
"bonus_summary": {
"applied_bonuses": [
{
"metric_earn": 97.0,
"bonus_display_name": "Order Rule Base",
"bonus_rule_description": ""
},
{
"metric_earn": 25.0,
"bonus_display_name": "Bonus Rule 1: Items",
"bonus_rule_description": "25 bonus points for purchasing qualified items"
},
{
"metric_earn": 45.0,
"bonus_display_name": "Bonus Rule 3: # of Qualified Items",
"bonus_rule_description": "45 bonus points for purchasing 3 qualified items"
}
],
"non_applied_bonuses": [],
"total_bonus": 167.0,
"metric": "point"
}
},
"accounts": [
{
"identifier": "A-024238492",
"valid": true,
"name": "John Smith",
"first_name": "John",
"last_name": "Smith",
"member_id": "A-024238492",
"new_metric_balance": "0",
"lifetime_metric_balance": "0",
"earned_metric_amount": 167
}
],
"details": {
"integration_id": "12345-OR_Bonus_20250522_01-20250522",
"linked_integration_id": "",
"metrics": {
"point": 167
},
"duplicate": false
},
"redeemed_tier_rewards": [],
"audit_trail": {}
}
